package com.witmore.neutron.ai.web.wechat.service;

import com.jk.mp.wx.response.WechatAuthAccessToken;
import com.witmore.neutron.ai.db.entity.UserDO;
import com.witmore.neutron.ai.web.wechat.dto.WechatUserInfo;

/**
 * 微信网页授权服务接口（仅处理code之后的步骤）
 * Author: 豆子高
 * Date: 2025/01/21
 */
public interface WechatOAuthService {

    /**
     * 通过code换取网页授权access_token
     *
     * @param code 授权码
     * @return WechatAccessToken
     */
    WechatAuthAccessToken getAccessToken(String code);

    /**
     * 通过access_token获取用户信息
     *
     * @param accessToken 网页授权接口调用凭证
     * @param openid      用户的唯一标识
     * @return WechatUserInfo
     */
    WechatUserInfo getUserInfo(String accessToken, String openid);

    /**
     * 刷新access_token
     *
     * @param refreshToken 刷新token
     * @return WechatAccessToken
     */
    WechatAuthAccessToken refreshAccessToken(String refreshToken);

    /**
     * 检验授权凭证（access_token）是否有效
     *
     * @param accessToken 网页授权接口调用凭证
     * @param openid      用户的唯一标识
     * @return 是否有效
     */
    boolean isAccessTokenValid(String accessToken, String openid);

    /**
     * 处理微信授权登录，创建或更新用户信息
     *
     * @param wechatUserInfo 微信用户信息
     * @return 用户实体
     */
    UserDO processWechatLogin(WechatUserInfo wechatUserInfo);

    /**
     * 获取有效的access_token（带缓存和自动刷新机制）
     *
     * @param code 授权码（首次获取时使用）
     * @param openid 用户openid（刷新token时使用）
     * @return WechatAuthAccessToken
     */
    WechatAuthAccessToken getValidAccessToken(String code, String openid);

    /**
     * 强制刷新并缓存access_token
     *
     * @param openid 用户openid
     * @return WechatAuthAccessToken
     */
    WechatAuthAccessToken refreshAndCacheAccessToken(String openid);
}
